Collection of Tools & Utilities/Collection of Tools and Utilities.iso/basic/pbc22a.zip/PBCLONE.DOC

Text File | 1993-04-25 | 54KB | 1,160 lines

                     The PBClone Library
                   =---------------------=
                         Version 2.2

    PBCLONE  Copyright (c) 1990-1993  Thomas G. Hanlin III



Use of LIBMAT or LIBWIZ is strongly recommended for creating
the initial PBClone library.  You should be able to get these
utilities from the same place you got this library.

This is PBClone, a library of over 610 assembly language and
BASIC routines for use with Microsoft's BASIC compilers:
Bascom, PDS, QuickBasic and Visual BASIC for DOS.  The PBClone
collection is copyrighted and may be distributed only under the
following conditions:

   All PBClone files must be distributed together as a unit.
   No files may be altered, added, or deleted from this unit.
   Assembly language source code may not be distributed.

YOU USE THIS LIBRARY AT YOUR OWN RISK.  I have tested it on my
own computer, but I will not assume any responsibility for any
problems which PBClone may cause you.  If you do run into a
problem, please let me know about it, and I will do my best to
verify and repair it.

It is expected that if you find PBClone useful, you will
register your copy.  You may not use PBClone routines in
programs intended for sale unless you have registered.

Registration gets you the latest version of PBClone, complete
with full source code.  The assembly language code is designed
for MASM 6.0 and may require alteration for other assemblers.

You will need to have a complete set of PBClone .OBJ files for
LibWiz to work.  Create a fresh subdirectory and extract the
BASIC sources from PBC$BAS.ZIP (or .LZH, etc).  Compile them
all.  The following DOS command will do it:

   FOR %x IN (*.BAS) DO BC %x /o;

Now extract the .OBJ files from PBC$MAIN.LIB into the same
directory, using the UnLib utility that comes with LibWiz.
Finally, extract the .OBJ files from PBC$NEAR.LIB as well. This
gives you a complete set of .OBJs for PBClone, allowing LibWiz
to create a custom PBClone library for you.

The VB-DOS compiler always uses far strings.  For it, you must
use the .OBJs from PBC$FAR.LIB instead of PBC$NEAR.LIB.

With PDS, you have a choice between near and far strings.  To
use far strings, use the /FS switch when compiling, and use the
.OBJs from PBC$FAR.LIB instead of PBC$NEAR.LIB.

                     Creating .QLB files



If you like to use the BASIC editor/environment, you will need
to create a .QLB version of the library to complement the .LIB
version.  LIBWIZ can do it for you, or you can do it manually.
This is done using the LINK.EXE utility that came with your
compiler.  The exact parameters differ slightly depending on
which version of the compiler you have.  For QuickBasic, it
looks something like this:

   LINK libname.LIB/Q/SE:1024,libname.QLB,NUL,BQLB45;

The BQLB45 file is for QuickBasic 4.5.  This should be replaced
by BQLB40 or BQLB41 for QuickBasic 4.0 (check your files to see
which you have).  For BASCOM 6.0-7.1, also called Professional
Development System or PDS, use QBXQLB instead of BQLB45.  For
VB-DOS, use VBDOSQLB instead of BQLB45.

Since you'll probably want to do this again in the future when
you get a new version of BasWiz or PBClone, I'd suggest you
create a batch file or alias to do the work for you.  If you
have 4DOS, an alias such as the following will do it:

   ALIAS QLB LINK %%1.LIB/Q/SE:1024,%%1.QLB,NUL,BQLB45;

In this case, you can do the conversion simply by typing:

   QLB libname

                     The TSR File Viewer



Since there are hundreds of routines in PBClone, it isn't
always exactly easy to remember which routine you want or how
to use it.  This is a particular problem when you're in the
middle of writing a program.  So, I've written a TSR file
viewer... it's crude, but it gets the job done.

Just type "FV" to install the TSR.  Alt-V activates it.  "FV
/D" removes it from memory.

     !!! ----== NOTE ==---- !!!
Please check FV with a nonessential application first!  It
appears to work fine in the QuickBasic environment, but it
locks up my favorite editor, so I can't guarantee that it will
behave properly in all circumstances.

First, FV will ask you for the file to view.  This may contain
drive and subdirectory information as well as the file name.
Second, you will be asked for a search string.  If you enter a
search string, viewing will start at the part of the file that
contains that search string.  If you just press enter, viewing
will start at the beginning of the file.  The file will be
presented to you one page at a time.  I suggest viewing
PBCLONE.DOC or PBCLONE.INF.

FV was written in BASIC using Crescent's P.D.Q. library, with
the "simplified" TSR handler (which doesn't seem to have been
entirely debugged).  Then again, TSRs are a tricky matter,
especially with BASIC...

                        General Notes



The initial version of PBClone had only one manual.  However,
since there are so many routines, I've split the manual into a
general documentation file and a reference manual.  You won't
want to print PBCLONE.MAN unless you have a lot of time and
printer paper!  In contrast, this file (PBCLONE.DOC) has been
kept small to allow ready printing.  It contains general notes,
cross-reference listings of the routines, and assorted charts.

Many of the routines in PBClone are similar to routines of the
same name in ADVBAS and/or ProBas.  The key here is "similar"--
they don't necessarily work the same way and may not produce
the same results.  If you intend to convert from ADVBAS or
ProBas to PBClone, read the documentation carefully.

When a PBClone returns a Boolean (on or off) value, it will
always be 0 if off, -1 if on; this is unlike ProBas, which
would often return any non-zero value for an "on" state.
Booleans passed to PBClone may still use any non-zero value to
indicate a "true" or "on" condition, however.

Critical error handling has been incorporated into all disk and
device routines.  You will never have to worry about "R>etry,
A>bort, I>gnore" again, so long as you use PBClone for your
disk and device management.

PBClone file handling is very flexible but may be confusing to
people used to BASIC's strongly-moded files.  PBClone file
handling is most similar to BASIC files opened in BINARY mode.
You may read or write any amount of information at a time.
After each read or write takes place, the file pointer is
updated appropriately, so you can use sequential access
techniques without further effort.  Random access is also
possible, using FSetLoc/FSetOfs/FSetRec to set the file pointer
position.  Those of you who are familiar with C or Pascal file
handling will notice strong similarities in this approach,
which is based on techniques that have long been standard in
the industry.

Many routines are available both as SUBprograms and as
FUNCTIONs.  The former is for compatibility with older programs
which were designed before BASIC was capable of using
FUNCTIONs.  You may use either, of course, although the
FUNCTION version of a routine is often more convenient.

                        General Notes



The PBClone library can be used in conjunction with other
libraries.  If there is a conflict in routine names between the
two libraries, the OBJTOOL utility can be used to rename one or
the other routine.  Due to the large size of PBClone, you will
probably need to select just the routines you need, rather than
combining the entire libraries, in order to avoid overflowing
LINK limitations.  OBJTOOL can help you find out which routines
are in what modules.  The LIB utility can be used to alter
existing libraries, or you can build your own custom libraries
from the ground up, using LibWiz.  See the LIB_BI.DOC and
LIBRARY.TXT files if you are not familiar with libraries.

LibMatic, LibWiz and ObjTool are included on the sampler disk
that comes with the registered version of PBClone.  They should
also be available at your local BBS.

If you have not used ADVBAS, ProBas, or PBClone before, you may
be unfamiliar with